<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>

<head>
<title>Table 4: Usage of 'clause.predicate.atom'</title>
</head>

<body bgcolor="white">


<p align="justify">
<b>Table 4: Usage of <code>clause.predicate.atom</code></b> This
complex DML attribute represents an <i>atomic predicate</i>, which is
a predicate that can be applied to the path attribute of a route.  The
atomic predicate indicates the path attribute to which it applies
(sub-attribute <code>attribute</code>), and includes an expression for
matching values of that attribute (sub-attribute
<code>matcher</code>).  Zero or more instances of <code>atom</code>
may be present within the <code>clause.predicate</code> attribute.
</p>

<p align="justify">
The <code>attribute</code> sub-attribute of <code>atom</code> is a
simple DML attribute whose value is a string which represents a BGP
path attribute to which an atomic predicate will be applied.  If the
value of the path attribute has multiple valid equivalent
representations (such as traditional and NHI values), then the value
of <code>attribute</code> will also indicate which representation of
the path attribute the atomic predicate is to be applied to.  In this
manner, policy filtering can be done on any representation of the
value of a path attribute.  Exactly one instance of this DML attribute
must be present in a <code>clause.predicate.atom</code> DML attribute.
</p>

<p align="justify">
Currently, the only acceptable values of <code>attribute</code> are
<code>origin</code>, <code>as_path</code>, <code>nhi_path</code>,
<code>next_hop_ip</code>, <code>next_hop_nhi</code>, <code>med</code>,
<code>local_pref</code>, <code>atomic_agg</code>,
<code>aggregator_ip</code>, <code>aggregator_nhi</code>,
<code>communities</code>, <code>originator_id_ip</code>,
<code>originator_id_nhi</code>, and <code>cluster_list</code>.  As of
the current implementation, the following path attributes have not
been implemented (and thus their associated filtering capabilities are
not yet useful): MULTI_EXIT_DISC (MED), ATOMIC_AGGREGATE, AGGREGATOR,
and COMMUNITIES.
</p>

<p align="justify">
The <code>matcher</code> sub-attribute of <code>atom</code> is a
simple DML attribute whose value is a string used for matching BGP
path attribute values during the evaluation of an atomic predicate.
An atomic predicate evaluates to <code>true</code> for a particular
path attribute if the value of the path attribute is a successful
match with the matcher string.  The interpretation of the string, and
what constitutes a successful match, differs for different values of
<code>attribute</code>.  It is often, though not always, a regular
expression, a list of values, or a range of values.  The string must
be enclosed in double-quotes, though the double-quotes themselves are
discarded before the string is used for matching.  Exactly one
instance of this DML attribute must be present in a
<code>clause.predicate.atom</code> DML attribute.  This table
describes the interpretation and usage of the values of
<code>matcher</code> given the various values of the corresponding
<code>attribute</code>.
</p>


<table align="center" border="1">

<tr>
<td align="center" valign="center">
<b><code>attribute</code> value</b>
</td>
<td align="center" valign="center">
<b><code>matcher</code> usage</b>
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>origin</code>
</td>
<td align="left" valign="center">
The only three meaningful values of <code>matcher</code> are
<code>"igp"</code>, <code>"egp"</code>, and <code>"inc"</code>.  They
correspond to the BGP ORIGIN path attribute values of IGP, EGP, and
INCOMPLETE, respectively.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>as_path</code>
</td>
<td align="left" valign="center">
Meaningful values of <code>matcher</code> are regular expressions for
matching an AS path in string form.  To be considered a successful
match, the given regular expression need only fit a substring of the
string form of the AS path.  (A full string match can always be forced
by using the standard regular expression characters <code>^</code> and
<code>$</code> appropriately.)  The string form of an AS path always
begins and ends with a space.  Following the beginning space is a
sequence of space-separated AS numbers.  Thus, the format of an AS
path string is
<code>"&nbsp;<i>n<sub>1</sub></i>&nbsp;<i>n<sub>2</sub></i>&nbsp;&#183;&#183;&#183;&nbsp;<i>n<sub>k</sub></i>&nbsp;"</code>
(the double-quotes are not part of the regular expression), where each
<code><i>n<sub>i</sub></i></code> is an AS number (integer), and
<code>k&nbsp;>=&nbsp;1</code>.  AS path segment type information
(AS_SET and AS_SEQUENCE) is lost when an AS path is represented in
this string form.  Ordering of segments is preserved, and ordering of
AS numbers within AS_SEQUENCE segments is preserved, but by
definition, AS numbers in AS_SET segments have no defined ordering,
and thus there is no pre-determined order in which the string will
contain AS numbers from such a segment.  For example, an AS path
consisting of the AS_SEQUENCE <code>(1&nbsp;2)</code> followed by the
AS_SET <code>{3&nbsp;4}</code> could be represented either by the
string <code>"&nbsp;1&nbsp;2&nbsp;3&nbsp;4&nbsp;"</code> or the string
<code>"&nbsp;1&nbsp;2&nbsp;4&nbsp;3&nbsp;"</code>, but no others.  The
standard regular expression syntax is supported for matching, along
with many useful extensions.  Refer to documentation for the <a
href="http://www.cacas.org/~wes/java/syntax.html"><code>gnu.regexp</code></a>
Java package for complete details.  As an example, one might set the
value of <code>matcher</code> to <code>"^&nbsp;3&nbsp;"</code> to
match all AS paths which begin with AS number <code>3</code>.  Note
the difference between <code>"^&nbsp;3&nbsp;"</code> and
<code>"&nbsp;3&nbsp;"</code>.  The latter will find a match in the AS
path string <code>"&nbsp;1&nbsp;2&nbsp;3&nbsp;4&nbsp;"</code>, while
the former will not.  Also note that <code>"^&nbsp;3"</code> will
match an AS path string such as
<code>"&nbsp;34&nbsp;701&nbsp;12&nbsp;"</code>, due to the fact that
there is no space following the <code>3</code>.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>nhi_path</code>
</td>
<td align="left" valign="center">
Meaningful values of <code>matcher</code> are regular expressions for
matching an AS path in string form.  The only difference between using
<code>as_path</code> and <code>nhi_path</code> is in the way that ASes
in the path are represented.  For <code>as_path</code>, each element
in the path is a traditional AS path number (an integer).  (See the
discussion of <code>as_path</code> above.)  For <code>nhi_path</code>,
each element in the path is an NHI address representing the AS.
Because each AS in SSFNet corresponds directly to a <code>Net</code>,
the NHI address of such a <code>Net</code> also serves as a unique AS
identifier.  The format of an AS path string using NHI addresses is
<code>"&nbsp;<i>n<sub>1</sub></i>&nbsp;<i>n<sub>2</sub></i>&nbsp;&#183;&#183;&#183;&nbsp;<i>n<sub>k</sub></i>&nbsp;"</code>
(the double-quotes are not part of the regular expression), where each
<code><i>n<sub>i</sub></i></code> is an NHI address, and
<code>k&nbsp;>=&nbsp;1</code>.  As an example, one might set the value
of <code>matcher</code> to <code>"^&nbsp;3:1:1&nbsp;"</code> to match
all AS paths which begin with the AS NHI identifier
<code>3:1:1</code>.  Refer to the preceding discussion of
<code>as_path</code> for additional information.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>next_hop_ip</code>
</td>
<td align="left" valign="center">
Meaningful values of <code>matcher</code> are regular expressions for
matching part or all of a route's next hop IP address, which is
represented in dotted-quad plus prefix length notation.  For example,
a value of <code>"^129\.1\.2\.0/28$"</code> would only match the exact
IP address <code>129.1.2.0/28</code>.  (Note that different IP
addresses which represent equivalent IP address blocks but which have
extra bits set, such as <code>129.1.2.1/28</code>, will not be matched
since matching is based only on the string comparison, not the actual
IP block represented.  This should not be a major concern in most
scenarios.)  The backslashes (<code>\</code>) are required since dot
(<code>.</code>) is a special character in regular expressions.  A
value of <code>"^129"</code> would match any IP address beginning in
<code>129</code>, and a value of <code>"/24$"</code> would match any
IP address ending in <code>/24</code>, etc.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>next_hop_nhi</code>
</td>
<td align="left" valign="center">
Meaningful values of <code>matcher</code> are regular expressions for
matching part or all of a route's next hop IP address, which is
represented by an NHI address.  For example, a value of
<code>"^11:2:1(0)$"</code> would only match the exact NHI address
<code>11:2:1(0)</code>, while a value of <code>"^11:"</code> would
match any NHI address whose first network ID is <code>11</code>.  Note
that a value of <code>"^11"</code> would also match an NHI address
such as <code>117:3(2)</code> because the trailing colon
(<code>:</code>) was omitted.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>med</code>
</td>
<td align="left" valign="center">
Not yet implemented.  A warning message is reported.  The usage notes
below will apply once implementation is complete.<br><br> A meaningful
value of <code>matcher</code> is either a (possibly empty) list of
integers or a range of integers.  A list of integers must either be
the empty string (<code>""</code>) or be of the form
<code>"<i>i<sub>1</sub></i>,<i>i<sub>2</sub></i>,...,<i>i<sub>k</sub></i>"</code>,
where <code>k >= 1</code>.  A range of integers must be of the form
<code>"[<i>j<sub>1</sub></i>,<i>j<sub>2</sub></i>]"</code>, where
<code><i>j<sub>1</sub></i></code> and/or
<code><i>j<sub>2</sub></i></code> may be omitted to indicate
open-ended ranges.  There can be no spaces in either form of the
expression.  If the actual MULTI_EXIT_DISC (MED) value appears in the
integer list or falls in the integer range, then there is a match.
Routes with no MED attribute can be matched by using an empty integer
list (<code>""</code>).  For example, <code>"1,4,7"</code> matches the
MED values <code>1</code>, <code>4</code> and <code>7</code>;
<code>"[4,9]"</code> matches the MED values <code>4</code> through
<code>9</code> inclusive; <code>"[3,]"</code> matches all MED values
greater than or equal to <code>3</code>; <code>""</code> matches
exactly those routes which do not have the MED attribute; and
<code>"[,]"</code> matches exactly those routes which do have the MED
attribute.  As of the release of this document, the MED path attribute
is unimplemented, and thus filtering on it is not yet meaningful.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>local_pref</code>
</td>
<td align="left" valign="center">
A meaningful value of <code>matcher</code> is either a (possibly
empty) list of integers or a range of integers.  The specification and
behavior of the <code>matcher</code> in this case is perfectly
analogous to the <code>med</code> case described previously.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>atomic_agg</code>
</td>
<td align="left" valign="center">
Not yet implemented.  A warning message is reported.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>aggregator</code>
</td>
<td align="left" valign="center">
Not yet implemented.  A warning message is reported.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>communities</code>
</td>
<td align="left" valign="center">
Not yet implemented.  A warning message is reported.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>originator_id_ip</code>
</td>
<td align="left" valign="center">
Meaningful values of <code>matcher</code> are regular expressions for
matching part or all of a route's originator ID.  In this case, an
originator ID is an IP address represented in dotted-quad plus prefix
length notation.  The specification and behavior of the
<code>matcher</code> in this case is perfectly analogous to the
<code>next_hop_ip</code> case described above.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>originator_id_nhi</code>
</td>
<td align="left" valign="center">
Meaningful values of <code>matcher</code> are regular expressions for
matching part or all of a route's originator ID.  In this case, an
originator ID is an NHI address.  The specification and behavior of
the <code>matcher</code> in this case is perfectly analogous to the
<code>next_hop_nhi</code> case described previously.
</td>
</tr>

<tr>
<td align="left" valign="center">
<code>cluster_list</code>
</td>
<td align="left" valign="center">
Meaningful values of <code>matcher</code> are regular expressions for
matching a cluster list in string form.  To be considered a successful
match, the given regular expression need only fit a substring of the
string form of the cluster list.  The string form of the cluster list
always begins and ends with a space.  Following the beginning space is
a sequence of space-separated cluster numbers.  Thus, the format of a
cluster list string is
<code>"&nbsp;<i>n<sub>1</sub></i>&nbsp;<i>n<sub>2</sub></i>&nbsp;&#183;&#183;&#183;&nbsp;<i>n<sub>k</sub></i>&nbsp;"</code>
(the double-quotes are not part of the regular expression), where each
<code><i>n<sub>i</sub></i></code> is a cluster number (integer), and
<code>k >= 1</code>.  Matching for cluster lists works the same way as
does matching for AS paths.  (See the above discussion regarding the
<code>attribute</code> value of <code>as_path</code>.)
</td>
</tr>

</table>


<br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br>
<br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br>


</body>
</html>
